import { PackageManagerTabs } from '@theme';

# Quick start

Get up to speed quickly with a new Rspack based project.

- [Create a new project](#create-a-new-project): Use the CLI to create a brand-new Rspack or Rsbuild project.
- [Migrating from existing projects](#migrating-from-existing-projects): Migrate from a webpack-based project to Rspack.

## Ecosystem

As a low-level bundler, Rspack has a rich ecosystem that includes various frameworks, tools, and solutions. These ecosystem projects cover different aspects from frameworks to development tools, meeting diverse development needs across scenarios and providing an out-of-the-box experience.

See the [Ecosystem](/guide/start/ecosystem) page to explore these ecosystem projects.

## Environment preparation

Rspack supports using [Node.js](https://nodejs.org/), [Deno](https://deno.com/), or [Bun](https://bun.sh/) as the JavaScript runtime.

You can refer to the following installation guides and choose one runtime:

- [Install Node.js](https://nodejs.org/en/download)
- [Install Bun](https://bun.com/docs/installation)
- [Install Deno](https://docs.deno.com/runtime/getting_started/installation/)

:::tip Version requirements

Rspack has the following Node.js version requirements:

- `@rspack/cli >= v1.0.0` requires Node.js 18.12.0 or higher.
- `@rspack/core >= v1.5.0` requires Node.js 18.12.0 or higher.
- `@rspack/core < v1.5.0` requires Node.js 16.0.0 or higher.

:::

## Create a new project

### Using Rsbuild

Rsbuild is a high-performance build tool powered by Rspack and developed by the Rspack team. It provides a set of thoughtfully designed default build configs, offering an out-of-the-box development experience and can fully unleash the performance advantages of Rspack.

We recommend using [Rsbuild](https://rsbuild.rs/) to create new projects, simply run the following command:

<PackageManagerTabs command="create rsbuild@latest" />

> For more information, refer to [Rsbuild - Quick start](https://rsbuild.rs/guide/start/quick-start).

### Using Rspack CLI

Rspack CLI is a tool comparable to webpack CLI, offering the basic `serve` and `build` commands.

Run the following command to create an Rspack CLI project:

<PackageManagerTabs command="create rspack@latest" />

Then follow the prompts in your terminal.

### Non-interactive mode

[create-rspack](https://www.npmjs.com/package/create-rspack) and [create-rsbuild](https://www.npmjs.com/package/create-rsbuild) support a non-interactive mode through command-line options. This mode lets you skip all prompts and create a project directly, which is useful for scripts, CI, and coding agents.

For example, the following command creates a React app in the `my-app` directory:

```bash
# Rspack CLI
npx -y create-rspack --dir my-app --template react

# Rsbuild
npx -y create-rsbuild --dir my-app --template react

# Using abbreviations
npx -y create-rsbuild -d my-app -t react
```

## Online examples

We provide an online example based on Rsbuild. The example gives an intuitive feel for the build performance of Rspack and the development experience of Rsbuild:

- [Rsbuild CodeSandbox example](https://codesandbox.io/p/github/rspack-contrib/rsbuild-codesandbox-example)

Here we also provide an online example based on Wasm and WebContainer on StackBlitz:

- [Rsbuild StackBlitz Example](https://stackblitz.com/~/github.com/rspack-contrib/rsbuild-stackblitz-example)

## Manual installation

Start by creating a project directory and generating an npm `package.json':

```bash
mkdir rspack-demo
cd rspack-demo
npm init -y
```

Then installing [@rspack/core](https://www.npmjs.com/package/@rspack/core) and [@rspack/cli](https://www.npmjs.com/package/@rspack/cli) as dev dependencies:

<PackageManagerTabs command="add @rspack/core @rspack/cli -D" />

Update your build scripts to use Rspack CLI:

```js title="package.json"
{
  "scripts": {
    "dev": "rspack dev",
    "build": "rspack build",
    "preview": "rspack preview"
  }
}
```

Next, see [Configure Rspack](/config/index) to learn about how to configure Rspack.

## Migrating from existing projects

If you need to migrate from an existing project to Rspack, you can refer to the following guides:

- [Migrating from webpack to Rspack](/guide/migration/webpack)
- [Migrating from webpack to Rsbuild](https://rsbuild.rs/guide/migration/webpack)
- [Migrating from Create React App to Rsbuild](https://rsbuild.rs/guide/migration/cra)
- [Migrating from Vue CLI to Rsbuild](https://rsbuild.rs/guide/migration/vue-cli)
- [Migrating from Vite to Rsbuild](https://rsbuild.rs/guide/migration/vite)
- [Migrating from Tsup to Rslib](https://rslib.rs/guide/migration/tsup)
- [Migrating from Storybook](/guide/migration/storybook)

## Install canary version

When you need to test or verify the features of Rspack that are not yet released to the stable version, you may need to use the canary version.

The canary version of Rspack has a `-canary` suffix in the package scope. For example, the canary package name of `@rspack/core` is `@rspack-canary/core`. To use these versions, you can configure the overrides of the package manager (npm/yarn/pnpm/bun).

Here is an example of using pnpm overrides:

```json title="package.json"
{
  "pnpm": {
    "overrides": {
      "@rspack/core": "npm:@rspack-canary/core@latest"
    },
    "peerDependencyRules": {
      "allowAny": ["@rspack/*"]
    }
  }
}
```

Rspack community also provides [install-rspack](https://github.com/rspack-contrib/install-rspack) tool to easily install canary version:

```shell
npx install-rspack --version latest # Install the latest version
npx install-rspack --version canary # Install the canary version
npx install-rspack --version 1.0.0-canary-d614005-20250101082730 # Install the specified canary version
```
